/**
 * 
 * ETH AI GAME LIBRARY
 * 
 * Author: Michael Jaworski
 * Copyright (c) Michael Jaworski 2010
 * http://code.google.com/p/eth/
 * 
 * Licence Agreement
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *	
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 *
 */

package lib.eth.core.interfaces
{
	/**
	 * an object that implements this interface may be used with the
	 * MemoryPool class. It can then take advantage of fast retreival
	 * and circumventing the gc. 
	 * 
	 * The class must reset and disable itself before invocation and recycling
	 * respectively. 
	 * 
	 * The flow of logic is as follows : 
	 * 
	 * constructor -> revive |
	 * hibernate |
	 * revive | 
	 * hibernate | 
	 * revive | ...
	 * 
	 * Note : constructor and hibernate will build/clear memory structures so
	 * they are empty or in a ready-for-use-state. the revive method
	 * will reset variables. 
	 * 
	 * The flow of logic : 
	 * 
	 * constructor;
	 * while exists
	 * 	revive
	 *  ... live ...
	 * 	hibernate
	 * 
	 * 
	 */ 
	public interface IRecyclable
	{
		/**
		 * called just after the object is invoked. used to 
		 * reset all variables, but not create data. Use the
		 * constructor or a separate initialize method to
		 * allocate any memory for this object. 
		 *
		 * @see eth.management.MemoryPool#invoke
		 *  
		 */ 
		function revive () : void;
		
		/**
		 * called just before an object is recycled. used to severe
		 * any connections with other objects so no active objects
		 * can make use of this object.
		 * 
		 * clean out (empty) any memory structures so they do not
		 * take space while this object is in hibernation. this should
		 * put the structures in the same state they were in after
		 * the initialize method was called.  
		 * 
		 * @see eth.management.MemoryPool#recycle
		 * 
		 */ 
		function hibernate () : void;
	}
}